---
title: 專案結構
description: 學習如何用 Astro 構築出一個專案。
i18nReady: true
---
import { FileTree } from '@astrojs/starlight/components'

使用 `create-astro` CLI 精靈來產生你的新 Astro 專案時，就會包含一些檔案和資料夾。至於其他項目則需要由你自己建立並加入到 Astro 既有的檔案結構。

這裡將介紹 Astro 專案是如何組織，且在你的新專案中會找到的一些檔案。

## 目錄及檔案

Astro 為你的專案準備固有的資料夾安排。每個 Astro 專案的根目錄應該包含下列目錄及檔案：

- `src/*` - 你的專案原始碼（元件、頁面、樣式等）。
- `public/*` - 你的非程式碼、未處理的資源（字體、圖示等）。
- `package.json` - 一個專案列表。
- `astro.config.mjs` - 一個 Astro 配置設定檔（建議）。
- `tsconfig.json` - 一個 TypeScript 配置設定檔（建議）。

### 範例專案樹狀圖

一個一般的 Astro 專案目錄應該看起來像這樣：

<FileTree>
- public/
  - robots.txt
  - favicon.svg
  - social-image.png
- src/
  - components/
    - Header.astro
    - Button.jsx
  - layouts/
    - PostLayout.astro
  - pages/
    - posts/
      - post1.md
      - post2.md
      - post3.md
    - index.astro
  - styles/
    - global.css
- astro.config.mjs
- package.json
- tsconfig.json
</FileTree>

### `src/`

你大多數的專案程式碼會放在 `src/` 資料夾內，其包含了：

- [頁面](/zh-tw/basics/astro-pages/)
- [版面](/zh-tw/basics/layouts/)
- [Astro 元件](/zh-tw/basics/astro-components/)
- [前端元件（React 等）](/zh-tw/guides/framework-components/)
- [樣式 （CSS、Sass）](/zh-tw/guides/styling/)
- [Markdown](/zh-tw/guides/markdown-content/)

Astro 會處理、最佳化並將你的 `src/` 捆起來建立最後瀏覽器會看到的網站。不像靜態的 `public/` 資料夾，Astro 會幫你建立並處理你 `src/` 的檔案。

一些檔案（如 Astro 元件）會被渲染成靜態的 HTML 而不會就所寫的內容傳到瀏覽器上。其他檔案（如 CSS）會被傳到瀏覽器上，但可能會為了效能表現而先被最佳化或捆進其他 CSS 檔案。

:::tip
雖然這裡提到許多 Astro 社群常見的慣例作法，但保留給 Astro 使用的目錄其實只有 `src/pages/` 和 `src/content/`。你可以依照適合自己的方式，自由決定其他目錄的命名和結構。
:::

### `src/components`

**元件** 是你 HTML 網頁中可重複使用的程式碼。它們可以是 [Astro 元件](/zh-tw/basics/astro-components/) 或是 [前端元件](/zh-tw/guides/framework-components/) 如 React 或 Vue。一般來說會在這個資料夾中組合和組織你專案所有的元件。

這是在 Astro 專案中普遍的慣例作法，但並非必須。就你自己喜好，自由自在地組織你的元件吧！

### `src/content`

`src/content/` 是保留給 Astro 的目錄，用來儲存[內容合集](/zh-tw/guides/content-collections/)和合集設定檔（非必要）。其他檔案不可放在此目錄底下。

### `src/layouts`

[版面](/zh-tw/basics/layouts/)是一個特殊的元件，其會將一些內容包進一個更大的網頁版面。這些很常被用來定義網頁如 [Astro 頁面](/zh-tw/basics/astro-pages/) 和 [Markdown 頁面](/zh-tw/guides/markdown-content/)的版面。

就如 `src/components` 一樣，這個目錄是一個普遍慣例作法並非必須。

### `src/pages`

[頁面](/zh-tw/basics/astro-pages/)是特殊的元件，用來建立網站的頁面。頁面可以是 Astro 元件，或代表網站部分內容的 Markdown 檔案。

:::caution
`src/pages` 在你的 Astro 專案是一個 **必須的** 子目錄。沒有它，你的網站不會有任何頁面或路由！
:::

### `src/styles`

這是一個普遍的慣例作法來儲存你的 CSS 或 Sass 檔案到一個 `src/styles` 目錄，但並非必須。只要你的樣式被存放在 `src/` 目錄內，並且有正確地引入，Astro 就會處理並最佳化這些檔案。

### `public/`

 `public/` 目錄是放置那些在 Astro 建立過程中不需要處理的檔案和資源。這些檔案會原封不動地複製到輸出的資料夾內。

這樣的處理讓 `public/` 是放置一般資源如圖片和字體或是特殊檔案像是 `robots.txt` 和 `manifest.webmanifest` 的理想地方。

你也能將 CSS 和 JavaScript 放到你的 `public/` 目錄裡，但要注意的是這些檔案在你最後輸出建立時並不會捆起來或是最佳化。

:::tip
一個原則，任何你自己寫的 CSS 或 JavaScript 應該待在你的 `src/` 目錄裡。
:::

### `package.json`

這是 JavaScript 套件管理器用來管理你依賴模組的一個檔案。它也定義了普遍會用來跑 Astro （例如： `npm start` 和 `npm run build` ）的腳本。

這裡有[兩種相依性](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file)你可以在 `package.json` 中指定： `dependencies` 和 `devDependencies` 。在大多情況下運作起來相同：Astro 在建立時會需要所有的相依性，而你的套件管理器會下載這兩個。我們推薦將你所有的依賴模組放在 `dependencies` 來開始，並只在你特別需要的時候才使用 `devDependencies` 。

若需要為你專案建立一個新的 `package.json` 檔案，可以看看[手動安裝](/zh-tw/install/manual/)教學來取得協助。

### `astro.config.mjs`

這個檔案會在每個入門範本建立且其包含了你 Astro 專案的配置選項。在此你可以指定用哪些整合、建立選項、伺服選項等等。

查看[設定方法](/zh-tw/reference/configuration-reference/)來了解更多在設定配置上的細節。

### `tsconfig.json`

這個檔案會在每個入門範本建立且其包含了你 Astro 專案的 TypeScript 配置選項。若沒有 `tsconfig.json` 這個檔案的話，部分功能（像是 npm 套件引入）在編輯器中不會被全部支援。

查看 [TypeScript 指南](/zh-tw/guides/typescript/)來了解更多設定細節。
